home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / amok98-106 / amok105 / english / headerinfo next >
Text File  |  1994-05-10  |  11KB  |  316 lines
  1. ===========================================================================
  2.                      AMOK - Amiga Modula & Oberon Klub
  3.  
  4.                      Standard Identifier for ProgInfo
  5.                        (Extract for Sourcecode)
  6. ===========================================================================
  7.  
  8. Header
  9.  
  10. All  AMOK  program  must  contain a header which incorporates all important
  11. information.
  12.  
  13. All  Modula-2  and  Oberon  programs must have a commentary in front of the
  14. keyword MODULE.  It should be highlighted through "***" or "---" lines, but
  15. please don't frame it (the last "*" in the row is in the way).
  16.  
  17. The  header  contains  different entries, all beginning with ":"keyword".".
  18. If there is not enough space in a line then repeat the ":"keyword"." in the
  19. next  line  and  continue  with  the entry.  The exact syntax is important,
  20. since otherwise the program is not able to find the entries.
  21.  
  22. The header must (!) contain at least the following entries:
  23.  
  24. :Program.       <name of the program>
  25. :Contents.      <short contents>
  26. :Author.        <full name of author, no pseudonym (!)>
  27. :Copyright.     <copyright of the module>
  28. :Language.      <language and if necessary extras>
  29. :Translator.    <name of the compiler/assembler with version>
  30. :History.       <version, autor, date, annotation>
  31.  
  32. If necessary add these items:
  33.  
  34. :Support.       <information about incorporation of other prorgrams/ideas>
  35. :Imports.       <imported modules except of the standard compiler modules>
  36. :Bugs.          <known bugs>
  37.  
  38. You can add these data voluntarily:
  39.  
  40. :Address.       <address of the author>
  41. :Phone.         <her/his Telephonnummer>
  42. :Update.        <information about changes, not documented in :History.>
  43. :Remark.        <any commentary>
  44. :Usage.         <usage e.g. for an CLI-Command>
  45.  
  46. Other  entries,  like  date,  shortcut, version shouldn't be used any more!
  47. Missing entries should be included or recontructed as soon as possible.
  48.  
  49.  
  50. Hints
  51.  
  52. There  exists no formal determination for the header.  But in order to have
  53. a single appearance you should obey the following rules.
  54.  
  55. Empy entries
  56.  
  57. You  can leave out some of the entries (except for the obligatory entries).
  58. Just  leave  out  everything including the keyword.  Empty entries can also
  59. contain  only  of  spaces, asteriks "*" or dashes "-".  Silly entries (e.g.
  60. ":Imports.  nothing until now") should be omitted.
  61.  
  62. :Program.
  63.  
  64. Here  you should enter the name of the program, which should be the same as
  65. the file name (with all extensions, e.g.  "Test.def").  If the program name
  66. does  not  identify  the program properly (e.g.  altered Module "Strings"),
  67. you should add an annotation right after the name.
  68.  
  69. :Contents.
  70.  
  71. Short  description of the program and its function.  The description should
  72. be  explanatory  and  must  not be a long version of the program name (e.g.
  73. NOT :
  74.  :Program.  InOut.def
  75.  :Contents. Definition modul Input/Output
  76. ).
  77.  
  78. :Author.
  79.  
  80. Please supply the full name.  Pseudonyms are not valid.  A program can also
  81. contain  more  than one author, e.g.  if a PC-program was converted for the
  82. AMIGA.
  83.  
  84. :Address.
  85.  
  86. The address of the author is facultativ.  It should contain street, number,
  87. post code, city and country.
  88.  
  89. :Phone.
  90.  
  91. The  telefon number of the author including prefix.  Additional information
  92. like  reachable  times  are valid.  If the program was written by more than
  93. one  author  (see above), so please submit the number of the author who can
  94. answer most of the questions.
  95.  
  96. :Copyright.
  97.  
  98. Here  you  can  state  if  your  program is Freeware or Shareware or if you
  99. release it Public Domain.
  100.  
  101. Freeware:
  102. - the author determines the way of copying
  103. - keeps all rights of his program
  104.  
  105. Shareware:
  106. - the author determines the way of copying
  107. - keeps all rights of his program and
  108. - you HAVE to pay a fee, if you use the program regularly (the Shareware
  109.   fee).
  110.  
  111. Annotations  like  "copy  it,  but leave my name in" are valid.  For longer
  112. descriptions there should exist a link to another file.
  113.  
  114. :Language.
  115.  
  116. In  most cases here will be written 'Modula-2' or 'Oberon'.  If the program
  117. uses  INLINE assembler code, then make a note.  The same should be done, if
  118. the  program  does  not use the modula standard.  This applies e.g.  if you
  119. use   the   type   conversion  of  ADDRESS/BPTR  in  M2Amiga  v3.2  or  the
  120. dereferencing  of BPTR pointers.  The normal usage of the BPTR is excluded.
  121. The  reason  herefore  is  to  warn people who want to use the program with
  122. other compilers.
  123.  
  124. :Translator.
  125.  
  126. Determines  the  compiler  (/assembler/interpreter)  and the version number
  127. (e.g.   v1.17  or v2.0).  It should be followed by compiler bugs, which are
  128. relevant for this program.
  129.  
  130. :History.
  131.  
  132. This  is  one of the most important entries.  It contains information about
  133. the  versions  of  the  program,  the dates, the author and the responsible
  134. person for the changes and an optional annotation.  Example:
  135.  
  136. :History.       v1.1 [bne] 29-Mar-89 bug in Init() fixed
  137.  
  138. There is an extra chapter for the version number.  Corresponding definition
  139. and  implementation  modules  should  have  always  the same version number
  140. (revision  number,  brach  number  and  key  may  be  different).  The date
  141. consists  of  the  day (one or two digits), the month's shortcut (Jan, Feb,
  142. Mar,  Apr,  May, Jun, Jul, Aug, Sep, Oct, Nov, Dec) (three letters) and the
  143. year  (two  or  four  digits).   The author's name is submitted in brackets
  144. (members of the club use the shortcut).
  145.  
  146. :Support.
  147.  
  148. In  order to be fair you should enter here all data about programs by other
  149. people where you have extracted ideas and bits & pieces.
  150.  
  151. :Imports.
  152.  
  153. If  you  import  other  modules than the standard ones, you have to include
  154. them  here.  If the program requires a special version then add the version
  155. number  directly  after  the name.  You can also create links to other AMOK
  156. disks.  Example:
  157.  
  158. :Imports.       MemSystem1.3 [bne], List [mif] AMOK#7
  159.  
  160. :Bugs.
  161.  
  162. Do  you  know about bugs in the module or are you not sure if the module is
  163. bugfree, then add a note here.  If possible then describe the bugs as exact
  164. as  possible  (e.g.  the faulty Procedure).  If the module has not been bug
  165. tested  completely  then you should warn the others:  ":Bugs.  not tested".
  166. If  you  supply  a  ":Bugs.   none" then you should be able to guarantee at
  167. least 99.9% correctness!
  168.  
  169. :Usage.
  170.  
  171. describes  the syntax of a CLI-Command and its arguments.  The usage should
  172. be described in EBNF or with a template (like in the DOS manual).
  173.  
  174.  
  175. Versions numbers
  176.  
  177. The  version  number  consists  normally  of two parts (version, revision),
  178. which  are  divided  by  a  dot.  The first fully running version should be
  179. called  1.0.   Any change should be followed by an increase in the revision
  180. number  with  1.9  <  1.10  <  1.11!   If  you have made major changes then
  181. increase  the version number and set the revision number to 0.  The version
  182. number  is  NOT a decimal, which is increased by 1/10.  A revision is NOT a
  183. tenth  of  a  version and a version does NOT contain 10 revisions!  Version
  184. and  revision  are  counted independently!!!  Version 1.09 is not valid and
  185. 1.10  (first  version,  tenth revision) is between 1.9 and 1.11 and ist not
  186. the  same as 1.1!!  There exist no "hundreth" versions.  If it is necessary
  187. to  include  an extra version in between then add an extra depth.  Example:
  188. There  exist all versions from 1.0 to 1.4 and somebody changes version 1.2.
  189. This  version has got the number 1.2.1 (a branch version).  You can display
  190. the version numbers as a tree:
  191.  
  192.       1.0
  193.  
  194.        |
  195.        V
  196.  
  197.       1.1
  198.  
  199.        |
  200.        V
  201.  
  202.       1.2
  203.  
  204.        |
  205.       / \
  206.      /   \
  207.     V     V
  208.  
  209.    1.3   1.2.1
  210.  
  211.     |      |
  212.     V      V
  213.  
  214.    1.4    1.2.2
  215.  
  216.     |      etc.
  217.  
  218.    ...
  219.  
  220.     |
  221.     V
  222.  
  223.    1.9
  224.  
  225.     |
  226.     V
  227.  
  228.    1.10
  229.  
  230.    etc.
  231.  
  232.  
  233. This  system  is  different  from  the  one used by the Big Blue, but it is
  234. easier  to understand, because it is quite clear, that 3.2 is the successor
  235. of  3.1  and  not of 3.19.  Versions and revisions can increase just as you
  236. like  -  Example:   the  libraries  of  the  old 1.2 Workbench did have the
  237. version number 33.180 (33rd version, 180th revision).
  238.  
  239. If  you want to make it even more differentiated, then you can add letters.
  240. They  are  optional  and don't tell anything about the order (e.g.  3.2d is
  241. the German and 3.2e is the English version).
  242.  
  243. The  idea by Bernd Preusing is now valid, where a implementation module can
  244. have a higher revision number than the corresponding definition module.  So
  245. you  don't  have to change the definition module each time you make a small
  246. change and save a lot of work with Make.
  247.  
  248.  
  249. Source code format
  250.  
  251. In  order  to keep your source code tidy (and Britain, of course, too), you
  252. should  use  the  following  format (it is not obligatory, but it should be
  253. easy to read):
  254.  
  255. * In each line there is only one logical command unit.
  256.  
  257. * global  procedures,  variables and constants stand right at the beginning
  258.   of the line.
  259.  
  260. * Declarations  and  procedure bodies should be shifted right of the CONST,
  261.   VAR, TYPE and PROCEDURE.
  262.  
  263. * Parts of the programm,  which are defined local or are in between certain
  264.   constructs, should be shifted TWO letters to the right.
  265.  
  266. * Corresponding  BEGIN  and  END,  IF,  ELSE  and END etc. should always be
  267.   placed  beneath each other.  If there are more than 25 lines (one screen)
  268.   between  END  and BEGIN etc. then add a remark after the END and say what
  269.   has ended there.
  270.  
  271. * Except for VAR, CONST, TYPE, BEGIN, DO, THEN, LOOP, RETURN and EXIT there
  272.   is always a semikolon at the end of each line.
  273.  
  274. * Elements  of  sets  and  RECORDs  don't  start  with  an  capital letter,
  275.   constants  can  start with either of both possibilities,  everything else
  276.   starts with capitals.  Joint words may also have them in the middle (e.g.
  277.   'CapitalWords').
  278.  
  279. * If  the  parameter list does not fit in one line (75 characters) then put
  280.   each parameter in a single line.
  281.  
  282. * Imports  are  sorted  alphabetically  by their module names.  If they are
  283.   longer  than  two  lines,  then  also  the  imported  objects  are sorted
  284.   alphabetically.
  285.  
  286. MODULE Example;
  287.  
  288. CONST
  289.   which = 106;
  290.  
  291.  
  292. PROCEDURE doSomething(this: Typ;
  293.                       VAR that: Art): BOOLEAN;
  294.   CONST
  295.     X = 1;
  296.     Y = 10;
  297.  
  298.   VAR
  299.     counter : INTEGER;
  300.  
  301.   BEGIN
  302.     FOR counter := X TO Y DO
  303.       Action(this, that);
  304.     END
  305.     RETURN that = which
  306.   END doSomething;
  307.  
  308.  
  309. BEGIN
  310.   IF doSomething(something, somethingElse) THEN
  311.     Aktion1;
  312.   ELSE
  313.     Aktion2;
  314.   END;
  315. END Example.
  316.